'\" t
.\"     Title: vfs_zfsacl
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 03/09/2023
.\"    Manual: System Administration tools
.\"    Source: Samba 4.17.6
.\"  Language: English
.\"
.TH "VFS_ZFSACL" "8" "03/09/2023" "Samba 4\&.17\&.6" "System Administration tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
vfs_zfsacl \- ZFS ACL samba module
.SH "SYNOPSIS"
.HP \w'\ 'u
vfs objects = zfsacl
.SH "DESCRIPTION"
.PP
This VFS module is part of the
\fBsamba\fR(7)
suite\&.
.PP
The
zfsacl
VFS module is the home for all ACL extensions that Samba requires for proper integration with ZFS\&.
.PP
Currently the zfsacl vfs module provides extensions in following areas :
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
NFSv4 ACL Interfaces with configurable options for ZFS
.RE
.sp
.RE
.PP
NOTE:This module follows the posix\-acl behaviour and hence allows permission stealing via chown\&. Samba might allow at a later point in time, to restrict the chown via this module as such restrictions are the responsibility of the underlying filesystem than of Samba\&.
.PP
This module makes use of the smb\&.conf parameter
\m[blue]\fBacl map full control = acl map full control\fR\m[]
When set to yes (the default), this parameter will add in the FILE_DELETE_CHILD bit on a returned ACE entry for a file (not a directory) that already contains all file permissions except for FILE_DELETE and FILE_DELETE_CHILD\&. This can prevent Windows applications that request GENERIC_ALL access from getting ACCESS_DENIED errors when running against a filesystem with NFSv4 compatible ACLs\&.
.PP
ZFS has mutiple dataset configuration parameters that determine ACL behavior\&. Although the nuances of these parameters are outside the scope of this manpage, the "aclmode" and "aclinherit" are of particular importance for samba shares\&. For datasets that are intended solely as Samba shares, "aclmode = restricted" and "aclinherit = passthrough" provide inheritance behavior most consistent with NTFS ACLs\&. A "restricted" aclmode prevents chmod() on files that have a non\-trivial ACL (one that cannot be expressed as a POSIX mode without loss of information)\&. Consult the relevant ZFS manpages for further information\&.
.PP
This module is stackable\&.
.PP
Since Samba 4\&.0 all options are per share options\&.
.SH "OPTIONS"
.PP
nfs4:mode = [ simple | special ]
.RS 4
Controls substitution of special IDs (OWNER@ and GROUP@) on NFS4 ACLs\&. The use of mode simple is recommended\&. In this mode only non inheriting ACL entries for the file owner and group are mapped to special IDs\&.
.sp
The following MODEs are understood by the module:
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
simple(default)
\- use OWNER@ and GROUP@ special IDs for non inheriting ACEs only\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
special(deprecated)
\- use OWNER@ and GROUP@ special IDs in ACEs for all file owner and group ACEs\&.
.RE
.sp
.RE
.RE
.PP
nfs4:acedup = [dontcare|reject|ignore|merge]
.RS 4
This parameter configures how Samba handles duplicate ACEs encountered in NFS4 ACLs\&. They allow creating duplicate ACEs with different bits for same ID, which may confuse the Windows clients\&.
.sp
Following is the behaviour of Samba for different values :
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
dontcare
\- copy the ACEs as they come
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
reject (deprecated)
\- stop operation and exit with error on ACL set op
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
ignore (deprecated)
\- don\*(Aqt include the second matching ACE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
merge (default)
\- bitwise OR the 2 ace\&.flag fields and 2 ace\&.mask fields of the 2 duplicate ACEs into 1 ACE
.RE
.sp
.RE
.RE
.PP
nfs4:chown = [yes|no]
.RS 4
This parameter allows enabling or disabling the chown supported by the underlying filesystem\&. This parameter should be enabled with care as it might leave your system insecure\&.
.sp
Some filesystems allow chown as a) giving b) stealing\&. It is the latter that is considered a risk\&.
.sp
Following is the behaviour of Samba for different values :
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
yes
\- Enable chown if as supported by the under filesystem
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no (default)
\- Disable chown
.RE
.sp
.RE
.RE
.PP
zfsacl:denymissingspecial = [yes|no]
.RS 4
Prevent users from setting an ACL that lacks NFSv4 special entries (owner@, group@, everyone@)\&. ZFS will automatically generate these these entries when calculating the inherited ACL of new files if the ACL of the parent directory lacks an inheriting special entry\&. This may result in user confusion and unexpected change in permissions of files and directories as the inherited ACL is generated\&.
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
yes
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no (default)
.RE
.sp
.RE
.RE
.PP
zfsacl:block_special = [yes|no]
.RS 4
Prevent ZFS from automatically adding NFSv4 special entries (owner@, group@, everyone@)\&. ZFS will automatically generate these these entries when calculating the inherited ACL of new files if the ACL of the parent directory lacks an inheriting special entry\&. This may result in user confusion and unexpected change in permissions of files and directories as the inherited ACL is generated\&. Blocking this behavior is achieved by setting an inheriting everyone@ that grants no permissions and not adding the entry to the file\*(Aqs Security Descriptor
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
yes (default)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no
.RE
.sp
.RE
.RE
.PP
zfsacl:map_dacl_protected = [yes|no]
.RS 4
If enabled and the ZFS ACL on the underlying filesystem does not contain any inherited access control entires, then set the SEC_DESC_DACL_PROTECTED flag on the Security Descriptor returned to SMB clients\&. This ensures correct Windows client behavior when disabling inheritance on directories\&.
.sp
Following is the behaviour of Samba for different values :
.RS
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
yes
\- Enable mapping to SEC_DESC_DACL_PROTECTED
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
no (default)
.RE
.sp
.RE
.RE
.SH "EXAMPLES"
.PP
A ZFS mount can be exported via Samba as follows :
.sp
.if n \{\
.RS 4
.\}
.nf
        \fI[samba_zfs_share]\fR
	\m[blue]\fBvfs objects = zfsacl\fR\m[]
	\m[blue]\fBpath = /test/zfs_mount\fR\m[]
	\m[blue]\fBnfs4: mode = simple\fR\m[]
	\m[blue]\fBnfs4: acedup = merge\fR\m[]
.fi
.if n \{\
.RE
.\}
.SH "VERSION"
.PP
This man page is part of version 4\&.17\&.6 of the Samba suite\&.
.SH "AUTHOR"
.PP
The original Samba software and related utilities were created by Andrew Tridgell\&. Samba is now developed by the Samba Team as an Open Source project similar to the way the Linux kernel is developed\&.
